Eine einheitliche Syntax, aus der sich AmigaGuide- und TeX-Dokumente und eine "ASCII-.doc" für die Druckerausgabe erzeugen lassen?
Tatsächlich bringt Texinfo diese Formate gut unter einen Hut. Erzeugbar sind auch sogenannte Info-Dateien für eine Art Online-Hilfe bei Unix, die auf dem Amiga zwar anwendbar aber kaum verbreitet ist. Nach HTML kann auch konvertiert werden (sagt die Anleitung), ein solches Proggi ist mir aber noch nicht über den Weg gelaufen.
Texinfo ist gut für die Dokumentation von Programmen geeignet, deshalb stelle ich es an dieser Stelle vor. Der Einstieg wird auch erklärt.
Der Autor eines Texinfo-Dokuments sollte gestalterisch eher defensiv veranlagt sein, die erzeugten AmigaGuide-Dokumente nutzen das System nicht aus (keine farbige Ausgabe). Dafür kann man die Struktur des Textes sehr genau vorgeben. Verfügbar sind Elemente wie Kapitel und Abschnitte, "Menüs" für Hypertext-Systeme, Ausschnitte / Zitate und z.B. Hervorhebungen, deshalb sollte physische Textauszeichnung wie fett, kursiv, unterstrichen vermieden werden. Sie sind aber auch möglich.
Texinfo (bzw. das zugehörige Formatierungsprogramm "makeinfo") habe ich von der Geek Gadgets 2 (Amiga Developer Environment). Im Aminet gibt es zum Beispiel text/hyper/mkguide155.lha, mit dem sich Texinfo-Dateien nach AmigaGuide konvertieren lassen.
Bedienung von Makeinfo:
"makeinfo --help" listet die verfügbaren Kommandozeilenoptionen.
Ein sinnvoller Aufruf, um einen AmigaGuide-Text zu erzeugen, wäre:
makeinfo --amiga-40 -o ram:x.guide x.texi
Makeinfo erzeugt auch AmigaGuide-Dokumente für OS 2.x (Argument --amiga) und für OS 3.0 (Argument --amiga-39). Es gibt da so kleine Unterschiede.
Mit --fill-column X läßt sich die Anzahl der Zeichen pro Zeile einstellen, die der erzeugte Text maximal haben darf (Standard ist 72).
Wenn man mit TeX eine DVI-Datei zur Ausgabe eines richtigen Handbuchs erzeugen will, muß man nichts umkonvertieren. Eine Texinfo-Datei sollte am Anfang das Kommando "\input texinfo" enthalten, das von makeinfo überlesen wird. TeX jedoch holt eine Art Include in den Speicher, das die Texinfo-Befehle zu TeX-Befehlen ummünzt. TeX kann den Rest der Texinfo-Datei ganz normal lesen. Die "texinfo.tex"-Datei, die TeX zu Beginn lesen muß, ist auf der Geek Gadgets CD dabei (etwas versteckt als "ADE/share/automake/texinfo.tex").
Die Grundelemente von Texinfo
Wer schon mal ein AmigaGuide-Dokument geschrieben hat, kennt sicher die Einteilung in Nodes. Am Bildschirm wird immer nur ein Node auf einmal präsentiert (ggf. darf der Benutzer scrollen), Querverweise rufen einen anderen Node auf. In einem Node ist die Inhaltsseite, in einem anderen evtl. der Index des Dokuments.
Für die Darstellung am Bildschirm kann makeinfo auch "Menüs", also Auflistungen von Querverweisen, erzeugen.
Im "TeX-Modus" (also beim Interpretieren durch TeX) werden die Nodes und Menüs sinnvollerweise überlesen, jedenfalls was den Satz von Text angeht (Referenzen werden natürlich trotzdem geprüft). Aber es gibt ja noch Befehle zur Strukturierung von Text, mit denen man Kapitel, Abschnitte, Unterabschnitte u.ä. definieren kann. Auch im Info/AmigaGuide-Modus sind sie nützlich (und sollten auch verwendet werden!). So wird ein einheitlicher Satz von Überschriften erreicht, TeX numeriert die Überschriften zusätzlich durch.
Wichtig zu Dokumentationszwecken sind auch Spezialbefehle, die Parameter, Funktionsnamen, Shortcuts u.ä. markieren. Beispiele und Sourcecodes lassen sich auch wiedergeben, ohne daß Texinfo darin herumpfuscht.
Eine Texinfo-Datei
Um einige Leistungen von Texinfo aufzuzeigen, folgt hier ein kleines Beispiel. Natürlich ist das nur ein kleiner Ausschnitt. Andererseits interpretiert makeinfo die Syntax auch nicht so vollständig, wie es möglich wäre, z.B. verweisen die Index-Einträge nur auf einen bestimmten Node, nicht auch auf eine Zeile innerhalb des Nodes, was bei langen Nodes wünschenswert wäre.
Die Texinfo.guide (in ADE/guide/) ist erstmal etwas abschreckend, da 600 KB groß, aber dank dieser kleinen Einführung sicher übersichtlicher. Achtung: man sollte die Datei vielleicht besser nicht in Multiview lesen, weil AmigaGuide die @-Zeichen von Texinfo für den Beginn eigener Befehle hält, wenn sie am Zeilenanfang stehen (und den Texinfo-Befehl dann nicht ausgibt).
Die Steuerbefehle beginnen alle mit "@", wie gleich ersichtlich wird. Sollen die Zeichen @, { und } ausgegeben werden, muß @@, @{ und @} benutzt werden.
"@c" macht den Rest der Zeile zum Kommentar, aber da ich hier ziemlich viel zu kommentieren habe, verwende ich an dieser Stelle kein @c. Der Texinfo-Quelltext ist eingerückt dargestellt. Die übersetzbare Datei bankraub.texi liegt bei.
\input texinfo
So geht es immer los, siehe oben.
@set VERSION 1.1
Hier wird eine Variable, ein Makro gesetzt (wie bei #define in C). Sie kann später mit @value ausgelesen werden.
@settitle Bankraub @value{VERSION}
Titel des Dokuments. Außerdem wird mit @value die Variable abgefragt, die eben gesetzt wurde.
@node Top, Über Bankraub, (dir), (dir)
Hier geht ein Node los. Folgende Parameter hat diese Zeile:
"Top": ist der Name des Nodes, wird von Bezügen etc. verwendet. Der Start-Node heißt immer "Top".
"Über Bankraub": So heißt der nächste Node (für die Blättersymbole)
"(dir)": An dieser Stelle steht der Name des Nodes, der der beim Rückwärtsblättern berücksichtigt wird. Da der erste Node keinen Vorgänger hat, steht hier "(dir)". makeinfo u.ä. Tools setzen dafür ggf. den Node einer anderen Datei ein.
"(dir)": Ähnlich wie beim vorhergehenden Parameter, nur daß es hier um den hierarchisch übergeordneten Node geht. -- Also den, über den diese Seite aufgerufen werden kann, aus Sicht der Menüs.
Bankraub, ein innovatives Programm!
@menu
* Über Bankraub:: Sinn und Zweck
* Aufruf:: Wie wird Bankraub @value{VERSION} benutzt?
* Bugs:: Probleme mit Bankraub.
* Index:: Index.
@end menu
Hier ist ein Menü zu sehen. Viele der Texinfo-Strukturen ("Umgebungen" werden sie genannt, analog zu TeX) sind in "@xy" und "@end xy" eingebettet.
Das Menü erstellt eine Liste von Links im Hypertextdokument und bleibt ohne Textausgabe in TeX.
Jeder Eintrag beginnt mit einem Stern. Dann folgt der Text, der im Querverweis-Knopf zu lesen ist, ein Doppelpunkt, und der Name des Nodes, zu dem der Knopf verweist. Weil man recht frei bei der Definition der Nodenamen ist (Leerzeichen erlaubt), sollte man so sinnvolle Nodenamen wählen, daß sie gleichzeitig als Beschreibungstext durchgehen. In diesem Fall muß man den Namen nur einmal schreiben, wie oben (sonst z.B. "* Über Bankraub:About:", wenn der Node "About" heißen würde).
Nach dem nächsten Doppelpunkt kommt die weitergehende Beschreibung, darf auch in der nächsten Zeile weitergehen (natürlich ohne Sternchen am Anfang).
@node Über Bankraub, Aufruf, Top, Top,
@chapter Über Bankraub
Mit Chapter erzeugt man ein neues Kapitel. In AmigaGuide wird der Überschriftentext mit Sternchen unterstrichen, TeX setzt ihn in einer größeren Schrift und beginnt eine neue Seite, etc. Verweise in TeX benutzen den Namen auch, a la "Siehe 2.1.1 Über Bankraub, Seite 123".
@section Zweck
Section ist eine untergeordnete Unterteilungsebene, ein Chapter kann mehrere Sections und eine Section mehrere Subsections enthalten...
@cindex Zweck
Hier wird dem "Concept Index" (Texinfo kennt mehrere Indizes, auch für Shortcuts, programminterne Befehle u.a.) ein neuer Eintrag hinzugefügt.
Bankraub liegt inzwischen in der Version @value{VERSION} vor. Das
Programm macht eine spezielle Art der Überweisung, die im übergreifenden
Computersystem der Banken programmiert ist, für den normalen Kunden
zugänglich.@footnote{Zwar ist der Trick, der in Bankraub ausgenutzt
wird, schon lange über die Eingabe geheimer Codes im Geldautomaten
nutzbar, bringt aber ein gewisses Aufsehen mit sich, da um die 200
Ziffern getippt werden müssen.}
Mit @footnote{Text} erstellt man Fußnoten. In Hypertext-Dokumenten kann man sowohl "echte" Fußnoten (der Text erscheint ganz unten im Node) und Verweise zu einem neuen Node mit dem Fußnotentext erhalten. Man entscheidet das über den Aufruf von makeinfo, mit dem Parameter "--footnote-style end" bzw. "--footnote-style separate".
@section Voraussetzungen
@cindex Voraussetzungen
@itemize @bullet
@item Visa-Fotokarte
@item Eigene Kontonummer beginnt mit @code{04}.
@end itemize
Das war eine Aufzählung! Zwischen "@itemize" und "@end itemize" kann man "@item" benutzen, das jeweils einen neuen Punkt (den @bullet) vor den Text eines einzelnen Aufzählungspunkts stellt. Bei @itemize kann man angeben, wie der Punkt aussehen soll, möglich wäre z.B. auch "@itemize -" für Spiegelstriche.
Die Itemize-Umgebungen lassen sich auch verschachteln, es wird trotzdem korrekt eingerückt.
Mit "@code" wird die "04" zu etwas ganz besonderem deklariert. Oft ist es schwierig, die richtige Markierungsart für eine bestimmte Information zu finden, aber Texinfo bietet ja so manches (mal in der Anleitung stöbern...)
@node Aufruf, Bugs, Über Bankraub, Top
@cindex Aufruf
@chapter Aufruf
Bankraub wird folgendermaßen aufgerufen:
@code{Bankraub} @var{MyAccount} @var{StealAccount} @var{Amount}
"@var{}" rahmt "metasyntaktische Variablen" :) ein, hier sind es einfach Platzhalter für einzusetzende Parameter.
Dabei haben die Parameter folgende Bedeutungen:
@multitable @columnfractions .3 .7
@item @var{MyAccount}
@tab die eigene Kontonummer und Bankleitzahl im Format @var{Konto}:@var{BLZ}
@item @var{StealAccount}
@tab wie bei @var{MyAccount}, jedoch das Konto, das etwas erleichtert werden soll.
@item @var{Amount}
@tab der Betrag des Geldtransfers in DM.
@strong{ACHTUNG:} Negative Beträge kehren die Transferrichtung um!
@end multitable
Toll, Texinfo kann auch ein wenig Tabellen machen, mit der "multitable"-Umgebung. Die hier vorgestellte Variante arbeitet mit festen Spaltenbreiten, in Bruchteilen der Gesamtbreite der Seite angegeben (die erste Spalte erhält 30%, die zweite 70% des bedruckbaren Platzes). Mit "@item" beginnt man eine neue Zeile, mit "@tab" schaltet man zur nächsten Spalte.
Die Anzahl der Spalten bestimmt man durch die Anzahl der Bruchteile, die man im Kopf angibt.
"@strong{}" hebt einen Text hervor, "@emph{}" ist eher als Betonung gedacht ("der Polizist schoß @emph{so} weit daneben, daß eine unbeteiligte Passantin...")
Bitte beachten Sie auch die @ref{Bugs,Programmfehler}
Das ist ein Querverweis. Zuerst wird der anzuspringende Node genannt, dann der Text, der im Knopf erscheinen soll. Es gibt noch die @xref-Variante, die zusätzlich ein "See ..." erzeugt.
@node Bugs, Index, Aufruf, Top
@cindex Bugs
@chapter Bugs (Programmfehler)
@cindex Lastschrifteinzug
@cindex Schnuppertransponder
Natürlich gehen wir davon aus, daß bei derart sensibler Software eine
Fehlfunktion den Anwender besonders ärgerlich stimmen wird. Denkbar wäre,
daß der Transfer durch einen Fehler im Bankserver-Schnuppertransponder
von der Bank als Lastschrifteinzug gedeutet wird. Der Bestohlene wird
sich wohl bei Ihnen melden. Daher möchten wir Ihnen den Rat geben, nur
Konton zu bestehlen, wo es sowieso nicht auffällt.
Umgekehrt können Sie natürlich besonders große Summen von Regierungskonten
abzweigen, um z.B. noch den Euro zu verhindern (Konvergenzkriterien), aber
das wird wohl kaum noch möglich sein.
@cindex Gefängnis
Jedenfalls gab es in der Vorgängerversion 1.0 einen kleinen Fehler, der
ein paar Anwender ins Gefängnis gebracht hat. Wir sind aber zuversichtlich,
den behoben zu haben...
@node Index, (dir), Bugs, Top
@chapter Index
Und da isser, von Texinfo selbst erzeugt:
@printindex cp
Mit "@printindex" wird ein Index ausgegeben. Ich sagte schon, daß es mehrere Indizes gibt. "cp" bezeichnet den Concept Index.
Das war der Querschnitt durch eine Texinfo-Datei. Die Datei selbst ist zum Herumprobieren separat dabei.
|
Inhaltsverzeichnis | |
| ©`98Der AmZeiger | ||